Create an advanced API Blueprint tutorial #279
Conversation
danielgtaylor
force-pushed
the
daniel/advanced-tutorial
branch
from
0b4228f to
90066ec
Compare
| "choice": "Swift", | ||
| "url": "/questions/1/choices/1", | ||
| "votes": 2048 | ||
| }, { |
There was a problem hiding this comment.
Can we just have 2 choices here? We don't need as many. We should try to make the Tutorials as small as possible
There was a problem hiding this comment.
This was copied directly from the first tutorial, but I can make it have fewer choices if it helps.
|
Looks good. Haven't checked closely for grammar issues. |
|
|
||
| + Schema | ||
|
|
||
| { |
There was a problem hiding this comment.
This tutorial produces a large JSON Schema, I wonder if we would be better off describing a simpler structure, perhaps the structure used on creating a question instead:
+ Request (application/json)
+ Body
{
"question": "Favourite language?"
"choices": [ "Swift", "Objective-C" ]
}
+ Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"question": { "type": "string }
"choices": {
"type": "array",
"items": { "type": "string" },
"minItems": 2
}
}
}
danielgtaylor
force-pushed
the
daniel/advanced-tutorial
branch
2 times, most recently
from
fcc271e to
3551977
Compare
|
@kylef @pksunkara I think I have addressed all of the feedback. Please take another look! I'll also look into the highlighting bugs soon, but that will be a different task. |
|
|
||
| Action request and response bodies can have associated schemas that describe the allowed structure of the body content. JSON bodies are typically described with [JSON Schema](http://json-schema.org/). Given a simple JSON response body we can describe the structure of the response with JSON Schema in a `+ Schema` section. | ||
|
|
||
| The schema can describe the type of each member, which members are required, default values, and support a number of other advanced features. Below is an example, taken from the API Blueprint tutorial blueprint: |
There was a problem hiding this comment.
The below example is not taken from API Blueprint tutorial.
danielgtaylor
force-pushed
the
daniel/advanced-tutorial
branch
from
3551977 to
1f20f01
Compare
|
@pksunkara addressed feedback. Thanks! |
|
|
||
| Once you start using MSON, you may find yourself wanting to reuse certain commonly used or nested data structure components. This is possible with the `## Data Structures` section. Attributes sections can then reference the data structures defined in the Data Structures or other resource sections by name. | ||
|
|
||
| For example, using the polls API question resource, we can split out the `Question` and `Choice` objects: |
There was a problem hiding this comment.
Isn't List All Questions part of Question Collection resource?
danielgtaylor
force-pushed
the
daniel/advanced-tutorial
branch
from
1f20f01 to
1614ff6
Compare
|
More feedback addressed. I can't seem to fix the syntax highlighting - it will need to be done along with a few other minor fixes in the syntax highlighter package. Will try and get to that soon, as it's quite annoying. |
Create an advanced API Blueprint tutorial
|
👍 |
This (draft) creates a new advanced API Blueprint tutorial covering JSON Schema, request and response attributes, data structures and relation types.
I'm pretty unsure of the relation types section, so please have a look and give me any feedback. Once this is ready, I'm thinking of making available a final full example
.apibfile with these features and linking the tutorial to the advanced tutorial somehow.Feedback will be much appreciated!